home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Languguage OS 2
/
Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO
/
gnu
/
elispman.lha
/
elispman
/
elisp-18
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1993-06-01
|
47KB
|
886 lines
This is Info file elisp, produced by Makeinfo-1.55 from the input file
elisp.texi.
This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
Emacs Version 19.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: elisp, Node: File Attributes, Prev: Truenames, Up: Information about Files
Other Information about Files
-----------------------------
This section describes the functions for getting detailed information
about a file, other than its contents. This information includes the
mode bits that control access permission, the owner and group numbers,
the number of names, the inode number, the size, and the times of access
and modification.
- Function: file-modes FILENAME
This function returns the mode bits of FILENAME, as an integer.
The mode bits are also called the file permissions, and they
specify access control in the usual Unix fashion. If the
low-order bit is 1, then the file is executable by all users, if
the second lowest-order bit is 1, then the file is writable by all
users, etc.
The highest value returnable is 4095 (7777 octal), meaning that
everyone has read, write, and execute permission, that the SUID bit
is set for both others and group, and that the sticky bit is set.
(file-modes "~/junk/diffs")
=> 492 ; Decimal integer.
(format "%o" 492)
=> 754 ; Convert to octal.
(set-file-modes "~/junk/diffs" 438)
=> nil
(format "%o" 438)
=> 666 ; Convert to octal.
% ls -l diffs
-rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
- Function: file-nlinks FILENAME
This functions returns the number of names (i.e., hard links) that
file FILENAME has. If the file does not exist, then this function
returns `nil'. Note that symbolic links have no effect on this
function, because they are not considered to be names of the files
they link to.
% ls -l foo*
-rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
-rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
(file-nlinks "foo")
=> 2
(file-nlinks "doesnt-exist")
=> nil
- Function: file-attributes FILENAME
This function returns a list of attributes of file FILENAME. If
the specified file cannot be opened, it returns `nil'.
The elements of the list, in order, are:
0. `t' for a directory, a string for a symbolic link (the name
linked to), or `nil' for a text file.
1. The number of names the file has. Alternate names, also
known as hard links, can be created by using the
`add-name-to-file' function (*note Changing File
Attributes::.).
2. The file's UID.
3. The file's GID.
4. The time of last access, as a list of two integers. The
first integer has the high-order 16 bits of time, the second
has the low 16 bits. (This is similar to the value of
`current-time'; see *Note Time of Day::.)
5. The time of last modification as a list of two integers (as
above).
6. The time of last status change as a list of two integers (as
above).
7. The size of the file in bytes.
8. The file's modes, as a string of ten letters or dashes as in
`ls -l'.
9. `t' if the file's GID would change if file were deleted and
recreated; `nil' otherwise.
10. The file's inode number.
11. The file system number of the file system that the file is
in. This element together with the file's inode number, give
enough information to distinguish any two files on the
system--no two files can have the same values for both of
these numbers.
For example, here are the file attributes for `files.texi':
(file-attributes "files.texi")
=> (nil
1
2235
75
(8489 20284)
(8489 20284)
(8489 20285)
14906
"-rw-rw-rw-"
nil
129500
-32252)
and here is how the result is interpreted:
`nil'
is neither a directory nor a symbolic link.
`1'
has only one name (the name `files.texi' in the current
default directory).
`2235'
is owned by the user with UID 2235.
`75'
is in the group with GID 75.
`(8489 20284)'
was last accessed on Aug 19 00:09. Unfortunately, you cannot
convert this number into a time string in Emacs.
`(8489 20284)'
was last modified on Aug 19 00:09.
`(8489 20285)'
last had its inode changed on Aug 19 00:09.
`14906'
is 14906 characters long.
`"-rw-rw-rw-"'
has a mode of read and write access for the owner, group, and
world.
`nil'
would retain the same GID if it were recreated.
`129500'
has an inode number of 129500.
`-32252'
is on file system number -32252.
File: elisp, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: Information about Files, Up: Files
Contents of Directories
=======================
A directory is a kind of file that contains other files entered under
various names. Directories are a feature of the file system.
Emacs can list the names of the files in a directory as a Lisp list,
or display the names in a buffer using the `ls' shell command. In the
latter case, it can optionally display information about each file,
depending on the value of switches passed to the `ls' command.
- Function: directory-files DIRECTORY &optional FULL-NAME MATCH-REGEXP
NOSORT
This function returns a list of the names of the files in the
directory DIRECTORY. By default, the list is in alphabetical
order.
If FULL-NAME is non-`nil', the function returns the files'
absolute file names. Otherwise, it returns just the names
relative to the specified directory.
If MATCH-REGEXP is non-`nil', this function returns only those
file names that contain that regular expression--the other file
names are discarded from the list.
If NOSORT is non-`nil', that inhibits sorting the list, so you get
the file names in no particular order. Use this if you want the
utmost possible speed and don't care what order the files are
processed in. If the order of processing is visible to the user,
then the user will probably be happier if you do sort the names.
(directory-files "~lewis")
=> ("#foo#" "#foo.el#" "." ".."
"dired-mods.el" "files.texi"
"files.texi.~1~")
An error is signaled if DIRECTORY is not the name of a directory
that can be read.
- Function: file-name-all-versions FILE DIRNAME
This function returns a list of all versions of the file named
FILE in directory DIRNAME.
- Function: insert-directory FILE SWITCHES &optional WILDCARD
FULL-DIRECTORY-P
This function inserts a directory listing for directory DIR,
formatted according to SWITCHES. It leaves point after the
inserted text.
The argument DIR may be either a directory name or a file
specification including wildcard characters. If WILDCARD is
non-`nil', that means treat FILE as a file specification with
wildcards.
If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
and switches do not contain `d', so that a full listing is
expected.
This function works by running a directory listing program whose
name is in the variable `insert-directory-program'. If WILDCARD is
non-`nil', it also runs the shell specified by `shell-file-name',
to expand the wildcards.
- Variable: insert-directory-program
This variable's value is the program to run to generate a
directory listing for the function `insert-directory'.
File: elisp, Node: Create/Delete Dirs, Next: Changing File Attributes, Prev: Contents of Directories, Up: Files
Creating and Deleting Directories
=================================
- Function: make-directory DIRNAME
This function creates a directory named DIRNAME.
- Function: delete-directory DIRNAME
This function deletes the directory named DIRNAME. The function
`delete-file' does not work for files that are directories; you
must use `delete-directory' in that case.
File: elisp, Node: Changing File Attributes, Next: File Names, Prev: Create/Delete Dirs, Up: Files
Changing File Names and Attributes
==================================
The functions in this section rename, copy, delete, link, and set the
modes of files.
In the functions that have an argument NEWNAME, if a file by the
name of NEWNAME already exists, the actions taken depend on the value
of the argument OK-IF-ALREADY-EXISTS:
* A `file-already-exists' error is signaled if OK-IF-ALREADY-EXISTS
is `nil'.
* Confirmation is requested if OK-IF-ALREADY-EXISTS is a number.
* No confirmation is requested if OK-IF-ALREADY-EXISTS is any other
value, in which case the old file is removed.
- Function: add-name-to-file OLDNAME NEWNAME &optional
OK-IF-ALREADY-EXISTS
This function gives the file named OLDNAME the additional name
NEWNAME. This means that NEWNAME becomes a new "hard link" to
OLDNAME.
In the first part of the following example, we list two files,
`foo' and `foo3'.
% ls -l fo*
-rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
-rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
Then we evaluate the form `(add-name-to-file "~/lewis/foo"
"~/lewis/foo2")'. Again we list the files. This shows two names,
`foo' and `foo2'.
(add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
=> nil
% ls -l fo*
-rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
-rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
-rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
Finally, we evaluate the following:
(add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
and list the files again. Now there are three names for one file:
`foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
(add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
=> nil
% ls -l fo*
-rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
-rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
-rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
This function is meaningless on VMS, where multiple names for one
file are not allowed.
See also `file-nlinks' in *Note File Attributes::.
- Command: rename-file FILENAME NEWNAME &optional OK-IF-ALREADY-EXISTS
This command renames the file FILENAME as NEWNAME.
If FILENAME has additional names aside from FILENAME, it continues
to have those names. In fact, adding the name NEWNAME with
`add-name-to-file' and then deleting FILENAME has the same effect
as renaming, aside from momentary intermediate states.
In an interactive call, this function prompts for FILENAME and
NEWNAME in the minibuffer; also, it requests confirmation if
NEWNAME already exists.
- Command: copy-file OLDNAME NEWNAME &optional OK-IF-EXISTS TIME
This command copies the file OLDNAME to NEWNAME. An error is
signaled if OLDNAME does not exist.
If TIME is non-`nil', then this functions gives the new file the
same last-modified time that the old one has. (This works on only
some operating systems.)
In an interactive call, this function prompts for FILENAME and
NEWNAME in the minibuffer; also, it requests confirmation if
NEWNAME already exists.
- Command: delete-file FILENAME
This command deletes the file FILENAME, like the shell command `rm
FILENAME'. If the file has multiple names, it continues to exist
under the other names.
A suitable kind of `file-error' error is signaled if the file does
not exist, or is not deletable. (In Unix, a file is deletable if
its directory is writable.)
See also `delete-directory' in *Note Create/Delete Dirs::.
- Command: make-symbolic-link FILENAME NEWNAME &optional OK-IF-EXISTS
This command makes a symbolic link to FILENAME, named NEWNAME.
This is like the shell command `ln -s FILENAME NEWNAME'.
In an interactive call, FILENAME and NEWNAME are read in the
minibuffer, and OK-IF-EXISTS is set to the numeric prefix argument.
- Function: define-logical-name VARNAME STRING
This function defines the logical name NAME to have the value
STRING. It is available only on VMS.
- Function: set-file-modes FILENAME MODE
This function sets mode bits of FILENAME to MODE (which must be an
integer). Only the 12 low bits of MODE are used.
- Function: set-default-file-modes MODE
This function sets the default file protection for new files
created by Emacs and its subprocesses. Every file created with
Emacs initially has this protection. On Unix, the default
protection is the bitwise complement of the "umask" value.
The argument MODE must be an integer. Only the 9 low bits of MODE
are used.
Saving a modified version of an existing file does not count as
creating the file; it does not change the file's mode, and does
not use the default file protection.
- Function: default-file-modes
This function returns the current default protection value.
File: elisp, Node: File Names, Next: Magic File Names, Prev: Changing File Attributes, Up: Files
File Names
==========
Files are generally referred to by their names, in Emacs as
elsewhere. File names in Emacs are represented as strings. The
functions that operate on a file all expect a file name argument.
In addition to operating on files themselves, Emacs Lisp programs
often need to operate on the names; i.e., to take them apart and to use
part of a name to construct related file names. This section describes
how to manipulate file names.
The functions in this section do not actually access files, so they
can operate on file names that do not refer to an existing file or
directory.
On VMS, all these functions understand both VMS file name syntax and
Unix syntax. This is so that all the standard Lisp libraries can
specify file names in Unix syntax and work properly on VMS without
change.
* Menu:
* File Name Components:: The directory part of a file name, and the rest.
* Directory Names:: A directory's name as a directory
is different from its name as a file.
* Relative File Names:: Some file names are relative to a current directory.
* File Name Expansion:: Converting relative file names to absolute ones.
* Unique File Names:: Generating names for temporary files.
* File Name Completion:: Finding the completions for a given file name.
File: elisp, Node: File Name Components, Next: Directory Names, Up: File Names
File Name Components
--------------------
The operating system groups files into directories. To specify a
file, you must specify the directory, and the file's name in that
directory. Therefore, a file name in Emacs is considered to have two
main parts: the "directory name" part, and the "nondirectory" part (or
"file name within the directory"). Either part may be empty.
Concatenating these two parts reproduces the original file name.
On Unix, the directory part is everything up to and including the
last slash; the nondirectory part is the rest. The rules in VMS syntax
are complicated.
For some purposes, the nondirectory part is further subdivided into
the name proper and the "version number". On Unix, only backup files
have version numbers in their names; on VMS, every file has a version
number, but most of the time the file name actually used in Emacs omits
the version number. Version numbers are found mostly in directory
lists.
- Function: file-name-directory FILENAME
This function returns the directory part of FILENAME (or `nil' if
FILENAME does not include a directory part). On Unix, the
function returns a string ending in a slash. On VMS, it returns a
string ending in one of the three characters `:', `]', or `>'.
(file-name-directory "lewis/foo") ; Unix example
=> "lewis/"
(file-name-directory "foo") ; Unix example
=> nil
(file-name-directory "[X]FOO.TMP") ; VMS example
=> "[X]"
- Function: file-name-nondirectory FILENAME
This function returns the nondirectory part of FILENAME.
(file-name-nondirectory "lewis/foo")
=> "foo"
(file-name-nondirectory "foo")
=> "foo"
;; The following example is accurate only on VMS.
(file-name-nondirectory "[X]FOO.TMP")
=> "FOO.TMP"
- Function: file-name-sans-versions FILENAME
This function returns FILENAME without any file version numbers,
backup version numbers, or trailing tildes.
(file-name-sans-versions "~rms/foo.~1~")
=> "~rms/foo"
(file-name-sans-versions "~rms/foo~")
=> "~rms/foo"
(file-name-sans-versions "~rms/foo")
=> "~rms/foo"
;; The following example applies to VMS only.
(file-name-sans-versions "foo;23")
=> "foo"
File: elisp, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
Directory Names
---------------
A "directory name" is the name of a directory. A directory is a
kind of file, and it has a file name, which is related to the directory
name but not identical to it. (This is not quite the same as the usual
Unix terminology.) These two different names for the same entity are
related by a syntactic transformation. On Unix, this is simple: a
directory name ends in a slash, whereas the directory's name as a file
lacks that slash. On VMS, the relationship is more complicated.
The difference between a directory name and its name as a file is
subtle but crucial. When an Emacs variable or function argument is
described as being a directory name, a file name of a directory is not
acceptable.
These two functions take a single argument, FILENAME, which must be
a string. Environment variable substitutions such as `$HOME', and the
symbols `~', and `..', are *not* expanded. Use `expand-file-name' or
`substitute-in-file-name' for that (*note File Name Expansion::.).
- Function: file-name-as-directory FILENAME
This function returns a string representing FILENAME in a form
that the operating system will interpret as the name of a
directory. In Unix, this means that a slash is appended to the
string. On VMS, the function converts a string of the form
`[X]Y.DIR.1' to the form `[X.Y]'.
(file-name-as-directory "~rms/lewis")
=> "~rms/lewis/"
- Function: directory-file-name DIRNAME
This function returns a string representing DIRNAME in a form that
the operating system will interpret as the name of a file. On
Unix, this means removing a final slash from the string. On VMS,
the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
(directory-file-name "~lewis/")
=> "~lewis"
Directory name abbreviations are useful for directories that are
normally accessed through symbolic links. Sometimes the users recognize
primarily the link's name as "the name" of the directory, and find it
annoying to see the directory's "real" name. If you define the link
name as an abbreviation for the "real" name, Emacs shows users the
abbreviation instead.
If you wish to convert a directory name to its abbreviation, use this
function:
- Function: abbreviate-file-name DIRNAME
This function applies abbreviations from `directory-abbrev-alist'
to its argument, and substitutes `~' for the user's home directory.
- Variable: directory-abbrev-alist
The variable `directory-abbrev-alist' contains an alist of
abbreviations to use for file directories. Each element has the
form `(FROM . TO)', and says to replace FROM with TO when it
appears in a directory name. The FROM string is actually a
regular expression; it should always start with `^'. The function
`abbreviate-file-name' performs these substitutions.
You can set this variable in `site-init.el' to describe the
abbreviations appropriate for your site.
Here's an example, from a system on which file system `/home/fsf'
and so on are normally accessed through symbolic links named `/fsf'
and so on.
(("^/home/fsf" . "/fsf")
("^/home/gp" . "/gp")
("^/home/gd" . "/gd"))
File: elisp, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
Absolute and Relative File Names
--------------------------------
All the directories in the file system form a tree starting at the
root directory. A file name can specify all the directory names
starting from the root of the tree; then it is called an "absolute"
file name. Or it can specify the position of the file in the tree
relative to a default directory; then it is called an "relative" file
name. On Unix, an absolute file name starts with a slash or a tilde
(`~'), and a relative one does not. The rules on VMS are complicated.
- Function: file-name-absolute-p FILENAME
This function returns `t' if file FILENAME is an absolute file
name, `nil' otherwise. On VMS, this function understands both
Unix syntax and VMS syntax.
(file-name-absolute-p "~rms/foo")
=> t
(file-name-absolute-p "rms/foo")
=> nil
(file-name-absolute-p "/user/rms/foo")
=> t
File: elisp, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
Functions that Expand Filenames
-------------------------------
"Expansion" of a file name means converting a relative file name to
an absolute one. Since this is done relative to a default directory,
you must specify the default directory name as well as the file name to
be expanded. Expansion also simplifies file names by eliminating
redundancies such as `./' and `NAME/../'.
- Function: expand-file-name FILENAME &optional DIRECTORY
This function converts FILENAME to an absolute file name. If
DIRECTORY is supplied, it is the directory to start with if
FILENAME is relative. (The value of DIRECTORY should itself be an
absolute, expanded file name; it should not start with `~'.)
Otherwise, the current buffer's value of `default-directory' is
used. For example:
(expand-file-name "foo")
=> "/xcssun/users/rms/lewis/foo"
(expand-file-name "../foo")
=> "/xcssun/users/rms/foo"
(expand-file-name "foo" "/usr/spool/")
=> "/usr/spool/foo"
(expand-file-name "$HOME/foo")
=> "/xcssun/users/rms/lewis/$HOME/foo"
Filenames containing `.' or `..' are simplified to their canonical
form:
(expand-file-name "bar/../foo")
=> "/xcssun/users/rms/lewis/foo"
`~/' is expanded into the user's home directory. A `/' or `~'
following a `/' is taken to be the start of an absolute file name
that overrides what precedes it, so everything before that `/' or
`~' is deleted. For example:
(expand-file-name
"/a1/gnu//usr/local/lib/emacs/etc/MACHINES")
=> "/usr/local/lib/emacs/etc/MACHINES"
(expand-file-name "/a1/gnu/~/foo")
=> "/xcssun/users/rms/foo"
In both cases, `/a1/gnu/' is discarded because an absolute file
name follows it.
Note that `expand-file-name' does *not* expand environment
variables; that is done only by `substitute-in-file-name'.
- Function: file-relative-name FILENAME DIRECTORY
This function does the inverse of expansion--it tries to return a
relative name which is equivalent to FILENAME when interpreted
relative to DIRECTORY. (If such a relative name would be longer
than the absolute name, it returns the absolute name instead.)
(file-relative-name "/foo/bar" "/foo/")
=> "bar")
(file-relative-name "/foo/bar" "/hack/")
=> "/foo/bar")
- Variable: default-directory
The value of this buffer-local variable is the default directory
for the current buffer. It is local in every buffer.
`expand-file-name' uses the default directory when its second
argument is `nil'.
On Unix systems, the value is always a string ending with a slash.
default-directory
=> "/user/lewis/manual/"
- Function: substitute-in-file-name FILENAME
This function replaces environment variables names in FILENAME
with the values to which they are set by the operating system.
Following standard Unix shell syntax, `$' is the prefix to
substitute an environment variable value.
The environment variable name is the series of alphanumeric
characters (including underscores) that follow the `$'. If the
character following the `$' is a `{', then the variable name is
everything up to the matching `}'.
Here we assume that the environment variable `HOME', which holds
the user's home directory name, has the value `/xcssun/users/rms'.
(substitute-in-file-name "$HOME/foo")
=> "/xcssun/users/rms/foo"
If a `~' or a `/' appears following a `/', after substitution,
everything before the following `/' is discarded:
(substitute-in-file-name "bar/~/foo")
=> "~/foo"
(substitute-in-file-name "/usr/local/$HOME/foo")
=> "/xcssun/users/rms/foo"
On VMS, `$' substitution is not done, so this function does nothing
on VMS except discard superfluous initial components as shown
above.
File: elisp, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
Generating Unique File Names
----------------------------
Some programs need to write temporary files. Here is the usual way
to construct a name for such a file:
(make-temp-name (concat "/tmp/" NAME-OF-APPLICATION))
Here we use the directory `/tmp/' because that is the standard place on
Unix for temporary files. The job of `make-temp-name' is to prevent
two different users or two different jobs from trying to use the same
name.
- Function: make-temp-name STRING
This function generates string that can be used as a unique name.
The name starts with the prefix STRING, and ends with a number that
is different in each Emacs job.
(make-temp-name "/tmp/foo")
=> "/tmp/foo021304"
To prevent conflicts among different application libraries run in
the same Emacs, each application should have its own STRING. The
number added to the end of the name distinguishes between the same
application running in different Emacs jobs.
File: elisp, Node: File Name Completion, Prev: Unique File Names, Up: File Names
File Name Completion
--------------------
This section describes low-level subroutines for completing a file
name. For other completion functions, see *Note Completion::.
- Function: file-name-all-completions PARTIAL-FILENAME DIRECTORY
This function returns a list of all possible completions for a file
whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
The order of the completions is the order of the files in the
directory, which is unpredictable and conveys no useful
information.
The argument PARTIAL-FILENAME must be a file name containing no
directory part and no slash. The current buffer's default
directory is prepended to DIRECTORY, if DIRECTORY is not an
absolute file name.
In the following example, suppose that the current default
directory, `~rms/lewis', has five files whose names begin with `f':
`foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
(file-name-all-completions "f" "")
=> ("foo" "file~" "file.c.~2~"
"file.c.~1~" "file.c")
(file-name-all-completions "fo" "")
=> ("foo")
- Function: file-name-completion FILENAME DIRECTORY
This function completes the file name FILENAME in directory
DIRECTORY. It returns the longest prefix common to all file names
in directory DIRECTORY that start with FILENAME.
If only one match exists and FILENAME matches it exactly, the
function returns `t'. The function returns `nil' if directory
DIRECTORY contains no name starting with FILENAME.
In the following example, suppose that the current default
directory has five files whose names begin with `f': `foo',
`file~', `file.c', `file.c.~1~', and `file.c.~2~'.
(file-name-completion "fi" "")
=> "file"
(file-name-completion "file.c.~1" "")
=> "file.c.~1~"
(file-name-completion "file.c.~1~" "")
=> t
(file-name-completion "file.c.~3" "")
=> nil
- User Option: completion-ignored-extensions
`file-name-completion' usually ignores file names that end in any
string in this list. It does not ignore them when all the possible
completions end in one of these suffixes or when a buffer showing
all possible completions is displayed.
A typical value might look like this:
completion-ignored-extensions
=> (".o" ".elc" "~" ".dvi")
File: elisp, Node: Magic File Names, Prev: File Names, Up: Files
Making Certain File Names "Magic"
=================================
You can implement special handling for certain file names. This is
called making those names "magic". You must supply a regular
expression to define the class of names (all those which match the
regular expression), plus a handler that implements all the primitive
Emacs file operations for file names that do match.
The value of `file-name-handler-alist' is a list of handlers,
together with regular expressions that decide when to apply each
handler. Each element has this form:
(REGEXP . HANDLER)
All the Emacs primitives for file access and file name transformation
check the given file name against `file-name-handler-alist'. If the
file name matches REGEXP, the primitives handle that file by calling
HANDLER.
The first argument given to HANDLER is the name of the primitive;
the remaining arguments are the arguments that were passed to that
operation. (The first of these arguments is typically the file name
itself.) For example, if you do this:
(file-exists-p FILENAME)
and FILENAME has handler HANDLER, then HANDLER is called like this:
(funcall HANDLER 'file-exists-p FILENAME)
Here are the operations that you can handle for a magic file name:
`add-name-to-file', `copy-file', `delete-directory',
`delete-file', `directory-file-name', `directory-files',
`dired-compress-file', `dired-uncache',
`expand-file-name', `file-accessible-directory-p',
`file-attributes', `file-directory-p',
`file-executable-p', `file-exists-p', `file-local-copy',
`file-modes', `file-name-all-completions',
`file-name-as-directory', `file-name-completion',
`file-name-directory', `file-name-nondirectory',
`file-name-sans-versions', `file-newer-than-file-p',
`file-readable-p', `file-symlink-p', `file-writable-p',
`insert-directory', `insert-file-contents',
`make-directory', `make-symbolic-link', `rename-file',
`set-file-modes', `set-visited-file-modtime',
`unhandled-file-name-directory',
`verify-visited-file-modtime', `write-region'.
The handler function must handle all of the above operations, and
possibly others to be added in the future. Therefore, it should always
reinvoke the ordinary Lisp primitive when it receives an operation it
does not recognize. Here's one way to do this:
(defun my-file-handler (operation &rest args)
;; First check for the specific operations
;; that we have special handling for.
(cond ((eq operation 'insert-file-contents) ...)
((eq operation 'write-region) ...)
...
;; Handle any operation we don't know about.
(t (let (file-name-handler-alist)
(apply operation args)))))
- Function: find-file-name-handler FILE
This function returns the handler function for file name FILE, or
`nil' if there is none.
- Function: file-local-copy FILENAME
This function copies file FILENAME to the local site, if it isn't
there already. If FILENAME specifies a "magic" file name which
programs outside Emacs cannot directly read or write, this copies
the contents to an ordinary file and returns that file's name.
If FILENAME is an ordinary file name, not magic, then this function
does nothing and returns `nil'.
- Function: unhandled-file-name-directory FILENAME
This function returns the name of a directory that is not magic.
It uses the directory part of FILENAME if that is not magic.
Otherwise, it asks the handler what to do.
This is used for running a subprocess; any subprocess must have a
non-magic directory to serve as its current directory.
File: elisp, Node: Backups and Auto-Saving, Next: Buffers, Prev: Files, Up: Top
Backups and Auto-Saving
***********************
Backup files and auto-save files are two methods by which Emacs tries
to protect the user from the consequences of crashes or of the user's
own errors. Auto-saving preserves the text from earlier in the current
editing session; backup files preserve file contents prior to the
current session.
* Menu:
* Backup Files:: How backup files are made; how their names are chosen.
* Auto-Saving:: How auto-save files are made; how their names are chosen.
* Reverting:: `revert-buffer', and how to customize what it does.
File: elisp, Node: Backup Files, Next: Auto-Saving, Prev: Backups and Auto-Saving, Up: Backups and Auto-Saving
Backup Files
============
A "backup file" is a copy of the old contents of a file you are
editing. Emacs makes a backup file the first time you save a buffer
into its visited file. Normally, this means that the backup file
contains the contents of the file as it was before the current editing
session. The contents of the backup file normally remain unchanged once
it exists.
Backups are usually made by renaming the visited file to a new name.
Optionally, you can specify that backup files should be made by copying
the visited file. This choice makes a difference for files with
multiple names; it also can affect whether the edited file remains owned
by the original owner or becomes owned by the user editing it.
By default, Emacs makes a single backup file for each file edited.
You can alternatively request numbered backups; then each new backup
file gets a new name. You can delete old numbered backups when you
don't want them any more, or Emacs can delete them automatically.
* Menu:
* Making Backups:: How Emacs makes backup files, and when.
* Rename or Copy:: Two alternatives: renaming the old file or copying it.
* Numbered Backups:: Keeping multiple backups for each source file.
* Backup Names:: How backup file names are computed; customization.
File: elisp, Node: Making Backups, Next: Rename or Copy, Prev: Backup Files, Up: Backup Files
Making Backup Files
-------------------
- Function: backup-buffer
This function makes a backup of the file visited by the current
buffer, if appropriate. It is called by `save-buffer' before
saving the buffer the first time.
- Variable: buffer-backed-up
This buffer-local variable indicates whether this buffer's file has
been backed up on account of this buffer. If it is non-`nil', then
the backup file has been written. Otherwise, the file should be
backed up when it is next saved (if backup files are enabled).
This is a permanent local; `kill-local-variables' does not alter
it.
- User Option: make-backup-files
This variable determines whether or not to make backup files. If
it is non-`nil', then Emacs creates a backup of each file when it
is saved for the first time.
The following example shows how to change the `make-backup-files'
variable only in the `RMAIL' buffer and not elsewhere. Setting it
`nil' stops Emacs from making backups of the `RMAIL' file, which
may save disk space. (You would put this code in your `.emacs'
file.)
(add-hook 'rmail-mode-hook
(function (lambda ()
(make-local-variable
'make-backup-files)
(setq make-backup-files nil))))
- Variable: backup-enable-predicate
This variable's value is a function to be called on certain
occasions to decide whether a there should be backup files for
file name FILENAME. If it returns `nil', backups are disabled.
Otherwise, backups are enabled (if `make-backup-files' is true).
File: elisp, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files
Backup by Renaming or by Copying?
---------------------------------
There are two ways that Emacs can make a backup file:
* Emacs can rename the original file so that it becomes a backup
file, and then write the buffer being saved into a new file.
After this procedure, any other names (i.e., hard links) of the
original file now refer to the backup file. The new file is owned
by the user doing the editing, and its group is the default for
new files written by the user in that directory.
* Emacs can copy the original file into a backup file, and then
overwrite the original file with new contents. After this
procedure, any other names (i.e., hard links) of the original file
still refer to the current version of the file. The file's owner
and group will be unchanged.
The first method, renaming, is the default.
The variable `backup-by-copying', if non-`nil', says to use the
second method, which is to copy the original file and overwrite it with
the new buffer contents. The variable `file-precious-flag', if
non-`nil', also has this effect (as a sideline of its main
significance). *Note Saving Buffers::.
The following two variables, when non-`nil', cause the second method
to be used in certain special cases. They have no effect on the
treatment of files that don't fall into the special cases.
- Variable: backup-by-copying
This variable controls whether to make backup files by copying.
If it is non-`nil', then Emacs always copies the current contents
of the file into the backup file before writing the buffer to be
saved to the file. (In many circumstances, this has the same
effect as `file-precious-flag'.)
- Variable: backup-by-copying-when-linked
This variable controls whether to make backups by copying for files
with multiple names (hard links). If it is non-`nil', then Emacs
uses copying to create backups for those files.
This variable is significant only if `backup-by-copying' is `nil',
since copying is always used when that variable is non-`nil'.
- Variable: backup-by-copying-when-mismatch
This variable controls whether to make backups by copying in cases
where renaming would change either the owner or the group of the
file. If it is non-`nil' then Emacs creates backups by copying in
such cases.
The value has no effect when renaming would not alter the owner or
group of the file; that is, for files which are owned by the user
and whose group matches the default for a new file created there
by the user.
This variable is significant only if `backup-by-copying' is `nil',
since copying is always used when that variable is non-`nil'.
File: elisp, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
Making and Deleting Numbered Backup Files
-----------------------------------------
If a file's name is `foo', the names of its numbered backup versions
are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
`foo.~3~', ..., `foo.~259~', and so on.
- User Option: version-control
This variable controls whether to make a single non-numbered backup
file or multiple numbered backups.
`nil'
Make numbered backups if the visited file already has
numbered backups; otherwise, do not.
`never'
Do not make numbered backups.
ANYTHING ELSE
Do make numbered backups.
The use of numbered backups ultimately leads to a large number of
backup versions, which must then be deleted. Emacs can do this
automatically.
- User Option: kept-new-versions
The value of this variable is the number of oldest versions to keep
when a new numbered backup is made. The newly made backup is
included in the count. The default value is 2.
- User Option: kept-old-versions
The value of this variable is the number of oldest versions to keep
when a new numbered backup is made. The default value is 2.
- User Option: dired-kept-versions
This variable plays a role in Dired's `dired-clean-directory'
(`.') command like that played by `kept-old-versions' when a
backup file is made. The default value is 2.
If there are backups numbered 1, 2, 3, 5, and 7, and both of these
variables have the value 2, then the backups numbered 1 and 2 are kept
as old versions and those numbered 5 and 7 are kept as new versions;
backup version 3 is deleted. The function `find-backup-file-name'
(*note Backup Names::.) is responsible for determining which backup
versions to delete, but does not delete them itself.
- User Option: trim-versions-without-asking
If this variable is non-`nil', then saving a file deletes excess
backup versions silently. Otherwise, it asks the user whether to
delete them.
File: elisp, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files
Naming Backup Files
-------------------
The functions in this section are documented mainly because you can
customize the naming conventions for backup files by redefining them.
If you change one, you probably need to change the rest.
- Function: backup-file-name-p FILENAME
This function returns a non-`nil' value if FILENAME is a possible
name for a backup file. A file with the name FILENAME need not
exist; the function just checks the name.
(backup-file-name-p "foo")
=> nil
(backup-file-name-p "foo~")
=> 3
The standard definition of this function is as follows:
(defun backup-file-name-p (file)
"Return non-nil if FILE is a backup file \
name (numeric or not)..."
(string-match "~$" file))
Thus, the function returns a non-`nil' value if the file name ends
with a `~'. (We use a backslash to split the documentation
string's first line into two lines in the text, but produce just
one line in the string itself.)
This simple expression is placed in a separate function to make it
easy to redefine for customization.
- Function: make-backup-file-name FILENAME
This function returns a string which is the name to use for a
non-numbered backup file for file FILENAME. On Unix, this is just
FILENAME with a tilde appended.
The standard definition of this function is as follows:
(defun make-backup-file-name (file)
"Create the non-numeric backup file name for FILE..."
(concat file "~"))
You can change the backup file naming convention by redefining this
function. In the following example, `make-backup-file-name' is
redefined to prepend a `.' as well as to append a tilde.
(defun make-backup-file-name (filename)
(concat "." filename "~"))
(make-backup-file-name "backups.texi")
=> ".backups.texi~"
- Function: find-backup-file-name FILENAME
This function computes the file name for a new backup file for
FILENAME. It may also propose certain existing backup files for
deletion. `find-backup-file-name' returns a list whose CAR is the
name for the new backup file and whose CDR is a list of backup
files whose deletion is proposed.
Two variables, `kept-old-versions' and `kept-new-versions',
determine which old backup versions should be kept (by excluding
them from the list of backup files ripe for deletion). *Note
Numbered Backups::.
In this example, the value says that `~rms/foo.~5~' is the name to
use for the new backup file, and `~rms/foo.~3~' is an "excess"
version that the caller should consider deleting now.
(find-backup-file-name "~rms/foo")
=> ("~rms/foo.~5~" "~rms/foo.~3~")
- Function: file-newest-backup FILENAME
This function returns the name of the most recent backup file for
FILENAME, or `nil' that file has no backup files.
Some file comparison commands use this function in order to compare
a file by default with its most recent backup.